home *** CD-ROM | disk | FTP | other *** search
/ The Atari Compendium / The Atari Compendium (Toad Computers) (1994).iso / files / internet / other / ka9q / nos / nosfiles.lzh / NNTPCLI.TXT < prev    next >
Encoding:
Text File  |  1992-12-07  |  12.6 KB  |  361 lines
  1. PC KA9Q NNTP Client                                CS 13-11-92
  2. ~~~~~~~~~~~~~~~~~~~
  3. The nntp commands are:
  4.  
  5. nntp directory [<spool-directory> [<control-directory>]]
  6.  
  7.      Allows specification of the spool directory (where the
  8.      news batches will be written) and the control directory
  9.      (where the history, data, kill and get files are kept). 
  10.      The control directory is discussed below.
  11.  
  12.      Default spool directory: /spool/mail
  13.      Default control directory: /spool/news
  14.  
  15. nntp groups [<group-list>]
  16.  
  17.      Allows specification of group list (see discussion
  18.      below).
  19.  
  20.      Default value: none
  21.  
  22. nntp addserver <server-name> <poll-interval>
  23.                                 [<time-window>] [<group-list>]
  24.  
  25.      Allows specification of news servers.  The poll-interval
  26.      is the interval in seconds between polls of the news
  27.      server (e.g., 1800 means poll the news server every 30
  28.      minutes).  The time-window specifies a time window for
  29.      polling.  The format is hour:min-hour:min (e.g.,
  30.      18:00-20:00 means only poll between 6pm and 8pm local
  31.      time).  The group-list is discussed below.
  32.  
  33.      Default value: none
  34.  
  35. nntp dropserver <server-name>
  36.  
  37.      Removes a news server from the polling list.
  38.  
  39. nntp kick <server-name>
  40.  
  41.      Forces a poll of the news server specified.  Has no
  42.      effect if a poll is already being attempted.
  43.  
  44. nntp listservers
  45.  
  46.      Lists the current news servers, the times until the next
  47.      poll and the polling intervals.
  48.  
  49. nntp batch [on|off [<buffers>]]
  50.  
  51.      When on, allows requests to be sent to the news server
  52.      before the replies from previous requests have been
  53.      received.  This makes things go faster.  The number of
  54.      buffers determines the number of requests that may be
  55.      outstanding.  Each buffer occupies around 1/2K of memory
  56.      space.
  57.  
  58.      Default value: off, 2 buffers
  59.  
  60. nntp newgroups [on|off]
  61.  
  62.      When on, the news server is asked for a list of new
  63.      groups created since the last successful poll.  The list
  64.      is appended to the file NEWGROUP in the control
  65.      directory.  No attempt is made to remove duplicate
  66.      entries.
  67.  
  68.      Default value: off
  69.  
  70. nntp trace [<trace-level>]
  71.  
  72.      Allows specification of trace information to be sent to
  73.      the screen.  The levels are defined as follows:
  74.  
  75.           0 - no tracing
  76.           1 - serious errors reported
  77.           2 - transient errors reported
  78.           3 - session progress reported
  79.           4 - actual received articles displayed
  80.  
  81.      All error messages are sent to the ka9q log file whatever
  82.      the tracing level.
  83.  
  84.      Default value: 1
  85.  
  86. nntp safety [on|off]
  87.  
  88.      When on, output files are closed after each article is
  89.      received.  This gives maximum protection if a machine
  90.      crash occurs but adds extra disk overhead.
  91.  
  92.      Default value: on
  93.  
  94. nntp verbose [on|off]
  95.  
  96.      When on, the following progress messages may be sent to
  97.      the screen:
  98.  
  99.           "Trying to connect to news server <server> ...."
  100.           "Connected to news server"
  101.  
  102.           "News available: <n> articles"
  103.           "News available: <n> new groups"
  104.           "News arrived (<n>/<n>): <newsgroups>, article:<msgid>"
  105.           "News duplicate: article <msgid>"
  106.           "News unavailable: article <msgid>"
  107.  
  108.           "News summary: <n> articles (<n> bytes) in <n> sec
  109.                                               (<n> bytes/sec)"
  110.           "New articles: <n> duplicate, <n> unavailable,
  111.                                     <n> headers, <n> complete"
  112.           "Get articles: <n> invalid, <n> unavailable,
  113.                                                  <n> received"
  114.           "History file: <n> entries, <n> complete scans"
  115.           "Throughput  : <n>/<n> bytes in <n>/<n> sec
  116.                                           (<n>/<n> bytes/sec)"
  117.           "Closing news session"
  118.  
  119.      When off, only the "News summary" message will be sent to
  120.      the screen.  The session statistics are sent to the ka9q
  121.      log file whatever the verbose setting.
  122.  
  123.      Default value: on
  124.  
  125.  
  126. Control Directory
  127. ~~~~~~~~~~~~~~~~~
  128. The following files may be created or read from the control
  129. directory:
  130.  
  131.      NNTP.DAT
  132.  
  133.           Used to record the time of the last successful poll
  134.           of each server.  Optionally used to specify the
  135.           newsgroup list for each server.  The format is
  136.           specified below.  Old server entries are not
  137.           automatically removed from this file.
  138.  
  139.      HISTORY
  140.  
  141.           Used to hold the message ids of articles received. 
  142.           This information is only required by the NNTP client
  143.           to prevent duplicate articles from being received. 
  144.           Old message ids are not automatically removed from
  145.           this file - it will grow forever if not manually
  146.           pruned.
  147.  
  148.      NEWGROUP
  149.  
  150.           Used to hold the names of new groups created on the
  151.           servers.  No attempt is made to prevent duplicate
  152.           names from being added.  Old group names are not
  153.           automatically removed from this file.
  154.  
  155.      KILL
  156.  
  157.           Used to hold patterns with which received header
  158.           lines are compared.  If certain patterns match then
  159.           the corresponding article bodies will not be
  160.           fetched.  The format is specified below.  If this
  161.           file exists then all new articles will be fetched in
  162.           two stages: header first then body.
  163.  
  164.      GET
  165.  
  166.           Used to hold message ids of articles that should be
  167.           unconditionally fetched (i.e., not subject to the
  168.           KILL file pattern matching).  The message ids of
  169.           articles that are unavailable will not be removed
  170.           from this file.  The file may therefore require
  171.           periodic flushing.
  172.  
  173.      *.TMP, *.LCK
  174.  
  175.           Temporary files created during an nntp session. 
  176.           These files should be automatically deleted.  The
  177.           *.LCK files should be manually deleted if there are
  178.           no active programs using files in the control
  179.           directory.
  180.  
  181.  
  182. Format of the NNTP.DAT file
  183. ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  184. There should be one line for each server.  This line will be
  185. automatically written after a successful nntp session and need
  186. not be created manually.  The line has the format:
  187.  
  188.      <server-name> <date> <time>
  189.  
  190. The first character of the server name must be in column one. 
  191. <date> has the form YYMMDD and <time> has the form HHMMSS. 
  192. The year is assumed to be in the closest century and the time
  193. is GMT.  For example:
  194.  
  195.      news.demon.co.uk 920909 073954
  196.  
  197. The newsgroups to be received from each server may optionally
  198. be specified on the lines following the line for the server. 
  199. Each line containing a newsgroup specification must begin with
  200. a whitespace character (e.g., space or tab).  One or more
  201. newsgroup entries may be put on a line, separated by
  202. whitespace or commas.  Multiple entries on one line will never
  203. be split across multiple requests.  Blank lines in the middle
  204. of the newsgroup list force the list to be split into multiple
  205. requests.  Blank lines before and after the newsgroup list are
  206. ignored.
  207.  
  208. Newsgroup entries may be complete names or may contain
  209. asterisks ("*") to allow pattern matches.  In addition, an
  210. exclamation mark ("!") as the first character will negate a
  211. match allowing newsgroups matching certain patterns to be
  212. ignored.  For example, "demon.*,!demon.test" will specify all
  213. groups in the demon hierarchy except demon.test.
  214.  
  215. General guidance:
  216.  
  217. 1    List all newsgroups one per line (except as noted below). 
  218.      This will minimise the number of requests made.
  219.  
  220. 2    Always list "omit" entries (entries beginning with an
  221.      exclamation mark) on the same line as the entries to
  222.      which they apply.
  223.  
  224. 3    Don't separate the newsgroup list with blank lines. 
  225.      However blank lines are ok before and after the list.
  226.  
  227. Example:
  228.  
  229. ----------------------------------------
  230. news.demon.co.uk 920909 073954
  231.  
  232.      demon.* !demon.test
  233.      comp.binaries.eniac
  234.      comp.sys.eniac
  235.      comp.unix.eniac
  236.      alt.humor
  237.      rec.pets rec.pets.gerbils
  238.  
  239. ----------------------------------------
  240.  
  241. Warning: be careful to leave the server line unchanged.  If
  242. the server line is not recognised then all news available may
  243. be requested.
  244.  
  245.  
  246. Format of the KILL file
  247. ~~~~~~~~~~~~~~~~~~~~~~~
  248. The kill file should contain one pattern per line.  Each
  249. header line received is compared with every pattern until a
  250. match occurs.  A match must be exact, with the first character
  251. of the pattern matching the first character of the header line
  252. and the last character of the pattern matching the last
  253. character of the header line.  Case is insignificant and
  254. whitespace is always represented by a single space character. 
  255. The pattern may contain special characters as follows:
  256.  
  257. !    If the first character of a pattern is "!" then the rest
  258.      of the line forms a "keep" pattern ("!" means don't
  259.      kill).  If any header line matches a keep pattern then
  260.      the article body will be fetched.
  261.  
  262.      If the first character of a pattern is not "!" then the
  263.      whole line forms a "kill" pattern.  If any header line
  264.      matches a kill pattern and no header line matches a keep
  265.      pattern then the article body will not be fetched.
  266.  
  267.      The "!" character has no significance in any other
  268.      position and will be matched literally.
  269.  
  270. ?    Matches any single character.
  271.  
  272. *    Matches zero or more characters.
  273.  
  274. [ ]  Matches any single character that appears within the
  275.      square brackets.  For example, [0123456789] will match
  276.      any single decimal digit.  The characters can be
  277.      specified as a range: [0-9] has the same meaning as the
  278.      previous example.
  279.  
  280. [^ ] Matches any single character that does not appear within
  281.      the square brackets.  For example, [^abc] will match any
  282.      single character except "a", "b" and "c".
  283.  
  284. \    Matches the following character literally.  For example,
  285.      \* will match a single asterisk and \\ will match a
  286.      single backslash.
  287.  
  288. The kill file patterns are all loaded into memory at the start
  289. of the news session - the kill file should therefore be kept
  290. as small as possible.  Offline article selection can be
  291. performed by creating a kill file containing the single
  292. pattern "*".  This will cause only headers to be fetched.  The
  293. message ids of the required articles can then be put in the
  294. get file for retrieval during the next news session.
  295.  
  296. Example:
  297.  
  298. ----------------------------------------
  299. Lines: *[0-9][0-9][0-9]*
  300. Newsgroups: *rec.pets*
  301. !Newsgroups: *rec.pets.gerbils*
  302. ----------------------------------------
  303.  
  304. The first line should kill any messages with more than 99
  305. lines.  Unfortunately some long messages do not contain a
  306. "Lines:" line so this is not foolproof.
  307.  
  308. The second line should kill any postings or cross-postings to
  309. the rec.pets hierarchy.
  310.  
  311. The third line will keep any postings to the rec.pets.gerbils
  312. hierarchy regardless of any matches with the other kill
  313. patterns.
  314.  
  315. Note that the header lines of killed articles are retained. 
  316. The full posting can be fetched later by putting the message
  317. id into the get file.
  318.  
  319.  
  320. Specifying newsgroups
  321. ~~~~~~~~~~~~~~~~~~~~~
  322. There are three methods of specifying the newsgroups to be
  323. received.
  324.  
  325. If there is a newsgroup list associated with the server in the
  326. NNTP.DAT file then that list will be used.  The list may be of
  327. any length.
  328.  
  329. If there is not a recognisable group list in the NNTP.DAT file
  330. then any groups specified with an NNTP ADDSERVER command will
  331. be used.  There is a maximum length for a group list specified
  332. in the NNTP ADDSERVER command of 488 characters (allowing one
  333. comma between each entry).
  334.  
  335. If there is no group list in the NNTP.DAT file and there are
  336. no groups specified with an NNTP ADDSERVER command then any
  337. groups specified in an NNTP GROUPS command will be used.  The
  338. maximum length of the group list here is also 488 characters.
  339.  
  340. If there are no groups specified anywhere then all groups will
  341. be requested.
  342.  
  343. Note that the group list specified with an NNTP GROUPS command
  344. replaces any existing list while the group list specified with
  345. an NNTP ADDSERVER command is appended to any existing list.
  346.  
  347.  
  348. Example settings for autoexec.net
  349. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  350.      nntp dir \spool\articles
  351.      nntp groups demon.*,!demon.test
  352.      nntp addserver news.demon.co.uk 1800
  353.      nntp trace 2
  354.      nntp batch on 4
  355.      nntp safety off
  356.  
  357. The list of newsgroups required is included in the NNTP.DAT
  358. file.  The NNTP GROUPS command is used as a back-up (if the
  359. NNTP.DAT file becomes unreadable, only the demon groups will
  360. be requested).
  361. ə